Skip to main content

Data Object Reference

This document provides a quick reference for the data structures used in the Velolink API. For detailed field definitions and GraphQL schemas, refer to the following documentation:

  • Historical Data - Complete vehicle state history
  • Journeys - Completed trips and rides
  • Events - Significant feature-related occurrences
  • Latest Data - Current vehicle states (same structure as real-time data)

Below are example data structures and field descriptions for each type:

Historical Data​

Historical data provides a record of vehicle states and feature usage over time. The data is returned in JSON format with the following structure:

{
  "data": {
    "historical": [
      {
        "dataId": "132147",
        "namespace": "valleytransport",
        "operator": "SC",
        "vehicleId": "188",
        "featureData": {
          "cyclist": {
            "type": "cyclist",
            "used": 1,
            "rideEnd": false,
            "capacity": 3,
            "deployed": true,
            "available": 2,
            "rideStart": false
          },
          "priority": {
            "type": "priority",
            "used": 1,
            "rideEnd": false,
            "capacity": 2,
            "available": 1,
            "rideStart": false
          }
        },
        "features": null,
        "routeId": "40",
        "tripId": "3754397",
        "lat": 37.40210723876953,
        "long": -122.07848358154297,
        "vehicleLat": 37.400856018066406,
        "vehicleLong": -122.07989501953125,
        "stopId": "65913",
        "stopSequence": 36,
        "stopLat": 37.403458,
        "stopLong": -122.078255,
        "timestamp": 1745971272404,
        "tod": "evening",
        "tzHour": 17,
        "tz": "America/Los_Angeles"
      }
    ]
  }
}

Data Fields​

  • data.historical: Array of historical data points
  • For each data point:
    • dataId: Unique identifier for the data point
    • namespace: Organization namespace
    • operator: Transit operator name
    • vehicleId: Unique identifier for the vehicle
    • featureData: Detailed feature information:
      • cyclist: Bicycle rack information
        • type: Feature type identifier
        • used: Number of spots in use
        • rideEnd: Boolean indicating end of ride
        • capacity: Total bicycle capacity
        • deployed: Boolean indicating if rack is deployed
        • available: Number of available spots
        • rideStart: Boolean indicating start of ride
      • priority: Priority seating information
        • type: Feature type identifier
        • used: Number of priority seats in use
        • rideEnd: Boolean indicating end of ride
        • capacity: Total priority seating capacity
        • available: Number of available priority seats
        • rideStart: Boolean indicating start of ride
    • features: Array of available features (may be null)
    • routeId: Current route identifier (may be empty string if not on route)
    • tripId: Current trip identifier (may be empty string if not on trip)
    • lat: Latitude coordinate of the data point
    • long: Longitude coordinate of the data point
    • vehicleLat: Vehicle's actual latitude coordinate from GTFSRT
    • vehicleLong: Vehicle's actual longitude coordinate from GTFSRT
    • stopId: Current stop identifier (may be empty string if not at stop)
    • stopSequence: Stop sequence number on the route
    • stopLat: Stop's latitude coordinate
    • stopLong: Stop's longitude coordinate
    • timestamp: Unix timestamp of the data point
    • tod: Time of day category (e.g., "evening")
    • tzHour: Hour in the local timezone
    • tz: Timezone identifier
info
  • All coordinates are in decimal degrees
  • Timestamps are Unix timestamps in milliseconds
  • Empty route, trip, and stop IDs indicate the vehicle is not currently in service or at a stop
  • Feature status (deployed, rideStart, rideEnd) helps track usage patterns
  • Time of day (tod) and timezone information helps with temporal analysis

Journeys​

Journeys data provides information about completed trips or rides for specific features (cyclist or priority). The data is returned in JSON format with the following structure:

{
  "data": {
    "journeys": [
      {
        "beginLat": 37.327766,
        "beginLong": -121.89366,
        "beginStopId": "64745",
        "beginTimestamp": "1745973072045",
        "beginTod": "evening",
        "beginTz": "America/Los_Angeles",
        "beginTzHour": 17,
        "beginmarkerid": null,
        "beginmarkerlat": 0,
        "beginmarkerlong": 0,
        "beginmarkername": null,
        "beginmarkerradius": 0,
        "distanceMeters": 4798.7915505433575,
        "durationMinutes": 180,
        "endLat": 37.36772918701172,
        "endLong": -121.91415405273438,
        "endStopId": "",
        "endTimestamp": "1745983872137",
        "endTod": "night",
        "endTz": "America/Los_Angeles",
        "endTzHour": 20,
        "endmarkerid": "01929109-cd3c-7337-8736-29eb07ec1b49",
        "endmarkerlat": 37.36333564420217,
        "endmarkerlong": -121.92888453145503,
        "endmarkername": "SJC Airport",
        "endmarkerradius": 1931,
        "journeyId": "0196841a-e6d0-777d-8fdc-422e4436173a",
        "namespace": "valleytransport",
        "operator": "SC",
        "routeId": "Blue Line",
        "tripId": "3771147",
        "type": "priority",
        "vehicleId": "915"
      }
    ]
  }
}

Data Fields​

  • data.journeys: Array of journey records
  • For each journey:
    • journeyId: Unique identifier for the journey
    • namespace: Organization namespace
    • operator: Transit operator name
    • vehicleId: Vehicle identifier
    • type: Type of journey ("cyclist" or "priority")
    • routeId: Route identifier
    • tripId: Trip identifier
    • distanceMeters: Total distance traveled in meters
    • durationMinutes: Duration of the journey in minutes
    • Begin location information:
      • beginLat: Starting latitude
      • beginLong: Starting longitude
      • beginStopId: Starting stop identifier (may be null)
      • beginTimestamp: Journey start timestamp
      • beginTod: Time of day at start
      • beginTz: Timezone at start
      • beginTzHour: Hour in local timezone at start
      • beginmarkerid: Starting marker identifier (may be null)
      • beginmarkerlat: Starting marker latitude
      • beginmarkerlong: Starting marker longitude
      • beginmarkername: Starting marker name
      • beginmarkerradius: Starting marker radius in meters
    • End location information:
      • endLat: Ending latitude
      • endLong: Ending longitude
      • endStopId: Ending stop identifier (may be empty string)
      • endTimestamp: Journey end timestamp
      • endTod: Time of day at end
      • endTz: Timezone at end
      • endTzHour: Hour in local timezone at end
      • endmarkerid: Ending marker identifier
      • endmarkerlat: Ending marker latitude
      • endmarkerlong: Ending marker longitude
      • endmarkername: Ending marker name
      • endmarkerradius: Ending marker radius in meters
info
  • All coordinates are in decimal degrees
  • Timestamps are Unix timestamps in milliseconds
  • Empty stop IDs indicate the journey didn't start/end at a designated stop
  • Marker information provides context about specific locations (e.g., airports, stations)
  • Journey type indicates whether it was a cyclist or priority seating journey
  • Distance and duration help analyze journey patterns and efficiency

Latest Data​

Latest data provides the most recent state of all vehicles in your namespace. The data is returned in JSON format with the following structure:

{
  "data": {
    "latest": {
      "133": {
        "vehicleId": "133",
        "namespace": "valleytransport",
        "operator": "SC",
        "routeId": "60",
        "tripId": "3759521",
        "features": ["cyclist", "priority"],
        "featureData": {
          "cyclist": {
            "deployed": false,
            "capacity": 3,
            "available": 3,
            "used": 0,
            "type": "cyclist",
            "rideStart": false,
            "rideEnd": false
          },
          "priority": {
            "capacity": 2,
            "available": 2,
            "used": 0,
            "type": "priority",
            "rideStart": false,
            "rideEnd": false
          }
        },
        "lat": 37.405662536621094,
        "long": -121.89591217041016,
        "timestamp": "2025-05-01T18:01:16.941Z",
        "events": []
      }
    }
  }
}

Data Fields​

  • data.latest: Object containing vehicle data, keyed by vehicle ID
  • For each vehicle:
    • vehicleId: Unique identifier for the vehicle
    • namespace: Organization namespace
    • operator: Transit operator name
    • routeId: Current route identifier (may be empty string if not on route)
    • tripId: Current trip identifier (may be empty string if not on trip)
    • features: Array of available features (e.g., ["cyclist", "priority"])
    • featureData: Detailed feature information:
      • cyclist: Bicycle rack information
        • deployed: Boolean indicating if rack is deployed
        • capacity: Total bicycle capacity
        • available: Number of available spots
        • used: Number of spots in use
        • type: Feature type identifier
        • rideStart: Boolean indicating start of ride
        • rideEnd: Boolean indicating end of ride
      • priority: Priority seating information
        • capacity: Total priority seating capacity
        • available: Number of available priority seats
        • used: Number of priority seats in use
        • type: Feature type identifier
        • rideStart: Boolean indicating start of ride
        • rideEnd: Boolean indicating end of ride
    • lat: Latitude coordinate
    • long: Longitude coordinate
    • timestamp: UTC timestamp of the data point
    • events: Array of recent events for the vehicle
info
  • All timestamps are in ISO 8601 format with UTC timezone
  • The data represents the most recent state for all vehicles in your namespace
  • Vehicles may have multiple features (e.g., cyclist racks and priority seating)
  • Empty route and trip IDs indicate the vehicle is not currently in service
  • Feature status (deployed, rideStart, rideEnd) helps track usage patterns

Events​

Events data provides information about significant occurrences related to vehicle features. The data is returned in JSON format with the following structure:

{
  "data": {
    "events": [
      {
        "eventId": "0196841a-e6d0-777d-8fdc-422e4436173a",
        "eventType": "Cyclist-Rack-Full",
        "lat": 37.40210723876953,
        "long": -122.07848358154297,
        "namespace": "valleytransport",
        "routeId": "Blue Line",
        "timestamp": "2025-05-01T18:01:16.941Z",
        "vehicleId": "915",
        "tripId": "3771147"
      }
    ]
  }
}

Data Fields​

  • data.events: Array of event records
  • For each event:
    • eventId: Unique identifier for the event
    • eventType: Type of event (e.g., "Cyclist-Rack-Full")
    • lat: Latitude coordinate at event time
    • long: Longitude coordinate at event time
    • namespace: Organization namespace
    • routeId: Route identifier
    • timestamp: UTC timestamp of the event
    • vehicleId: Vehicle identifier
    • tripId: Trip identifier
info
  • All coordinates are in decimal degrees
  • Timestamps are in ISO 8601 format with UTC timezone
  • Event types indicate specific conditions or state changes (e.g., rack full, ride start/end)